Vite Runner: 使用 Vite Environment API 运行 TypeScript 文件的现代化方案

背景

随着 vite-node 宣布完成使命并推荐使用 Vite 原生的 Environment API，以及 tsx 等传统方案在 Vite 项目中的局限性，我们探索并实现了一种基于 Vite Environment API 的 TypeScript 运行时方案。

核心思路

利用 Vite 的 ssrLoadModule API，创建临时的 Vite 服务器实例来即时编译和执行 TypeScript 文件，无需预先编译步骤。

实现方案

核心代码

            javascript
            
          
#!/usr/bin/env node

import { createServer } from 'vite'

/**
 * 使用 Vite 运行 TypeScript 文件
 */
async function runTypeScriptFile(filePath) {
  // 创建 Vite 服务器
  const server = await createServer({
    configFile: false,              // 不使用配置文件，简化设置
    server: { hmr: false },        // 禁用 HMR
    optimizeDeps: {
      noDiscovery: true,
      include: undefined
    },                             // 禁用依赖优化
    clearScreen: false,
    logLevel: 'silent',           // 静默模式
  })

  try {
    // 使用 Vite 的 SSR 功能加载并执行模块
    await server.ssrLoadModule(filePath)
  } finally {
    // 清理资源
    await server.close()
  }
}

/**
 * CLI 主函数
 */
async function main() {
  const args = process.argv.slice(2)

  if (args.length === 0) {
    process.exit(1)
  }

  const filePath = args[0]

  try {
    await runTypeScriptFile(filePath)
  } catch (error) {
    process.exit(1)
  }
}

// 运行主函数
main().catch(() => {})

使用方式

1. 作为项目脚本

            bash
            
          
# 保存为 run-ts.js
node run-ts.js src/example.ts

# 或在 package.json 中添加命令
{
  "scripts": {
    "run": "node run-ts.js"
  }
}

2. 命令行使用

            bash
            
pnpm run run src/example.ts

技术优势

与现有方案对比

特性	tsx	vite-node	Vite Runner (我们的方案)
安装	npm install tsx	npm install vite-node	内置 Vite
配置	简单	简单	极简
性能	良好	良好	优秀
插件生态	有限	Vite 插件	完整 Vite 生态
未来支持	持续维护	已废弃	官方推荐方向
项目一致性	独立工具	独立工具	与 Vite 项目完全一致

核心特性

✅ 零配置: 无需额外配置即可运行 ✅ 类型安全: 完整的 TypeScript 支持 ✅ ESM 支持: 现代 ES 模块语法 ✅ 异步支持: 支持 async/await ✅ 依赖解析: 自动解析 node_modules 依赖 ✅ 静默执行: 无多余日志输出 ✅ Vite 生态: 完全兼容 Vite 插件和配置

适用场景

最佳使用场景

Vite 项目: 已经使用 Vite 构建的项目

开发工具: 需要使用 Vite 插件生态的脚本

统一工具链: 希望运行时和构建时使用相同工具

复杂插件需求: 需要 Vue、React、CSS 预处理器等支持

不适合的场景

纯 TypeScript 项目（tsx 更合适）

简单脚本（tsx 配置更简单）

非 Vite 项目

前景展望

作为 npm 包的可能性

该方案可以封装成 npm 包发布，供社区使用：

            bash
            
          
# 包名建议
vite-run
vite-ts-runner
@vite/runner

# 用户使用
npm install -D vite-run
vite-run src/script.ts

包结构设计

            
            
          
vite-run/
├── package.json          # 包配置，包含 bin 字段
├── bin/
│   └── vite-run.js      # CLI 入口点
├── src/
│   └── index.ts         # 核心 API
├── dist/               # 编译输出
└── README.md          # 使用文档

高级功能扩展

监听模式: vite-run --watch script.ts

配置选项: 支持传入 vite 配置

调试模式: 详细的错误信息和堆栈跟踪

性能优化: 服务器实例复用和缓存

技术实现细节

关键 API

createServer(): 创建 Vite 服务器实例

ssrLoadModule(): 加载并执行模块

环境隔离: 每次运行创建独立的服务器实例

性能考虑

服务器启动开销较大，适合开发环境

可通过服务器复用优化性能

内存使用比 tsx 稍高，但功能更强大

错误处理

静默模式避免 Vite 内部日志干扰

统一的错误退出机制

资源清理保证

结论

这个方案填补了 vite-node 退役后的空白，为 Vite 项目提供了现代化的 TypeScript 运行时解决方案。虽然目前是自实现，但其技术方向与 Vite 官方推荐一致，具有很好的发展前景。

对于已经在使用 Vite 的项目，这是一个比 tsx 更合适的选择，能够保持工具链的一致性和完整性。

下一步计划

封装成 npm 包: 发布到 npm 供社区使用

功能完善: 添加监听模式、配置选项等

性能优化: 服务器实例复用、缓存机制

社区反馈: 收集用户反馈，持续改进

这是一个探索性的技术方案，代表了 TypeScript 运行时工具在 Vite 生态中的发展方向。